Resco Locker is
---------------
a utility that keeps applications locked in memory on NVFS systems. 

This greatly increases the system stability and may increase the device performance -
mainly on the LifeDrive.


Requirements
-------------
Palm OS 5+

Use only on NVFS-based handhelds, i.e. Tungsten T5 and E2, LifeDrive, Treo T650.
(And probably all Palm handhelds that will appear in the future.)

Palm TX is supported since v1.20. (TX is special in one aspect: Locking itself is not enough
to prevent flushing the DB from the DbCache - the database must be additionally protected.)

While Resco Locker can be formally used on non-NVFS systems, it cannot do anything useful here. 


Why to use Resco Locker?
------------------------
Main reason is the safety.
NVFS brought changes to the Palm OS programming and not all applications reflected them.
(Those that were last time updated prior to NVFS release [Oct-2004], could not.) 
One of the most frequent problems is that the Palm databases are no longer fixed. 
That's exactly the area that is targeted by Resco Locker.

As a side effect, applications locked in memory need less time to load, which in turn may 
increase the performance of your handheld. Use this argument with care because:
- In most cases the speed effect is difficult to observe.
- By locking too many applications, the space left for other applications becomes smaller.
  (RLocker limit for locking is 4 MB. The device cache has about 10MB.)


Comparison to other apps
------------------------

SharkCache has a similar functionality.
There are minor differences in that RLocker performs double-locking (safer) and locks only 1st record
of the data databases while SC locks all records. (Difficult to say, which procedure is better.)

RLocker performs immediate lock/unlock, while SharkCache leaves the locking for the reset.

RLocker has better GUI and offers also DA's (Desk Accessories) locking.


Typical  use
-------------

1. Options dialog: Enable RLocker and switch on 'Only lock code' 
2. Action trigger > Select Defaults 
3. Unselect apps that you know are safe 
4. Press Lock button 
5. Test 
6. If satisfactory, switch on 'Restore locks after reset' in the Options dialog 
7. Otherwise read Help.txt (part of the .zip installer)


Usage
------

- Lock
Select one or more applications by tapping the respective rows and tap the Lock button. 
The locking is performed immediately. 

- Unlock
To unlock repeat the same procedure and tap the Unlock button.

- Action trigger offers selection commands (e.g. Select All) and Column Setup dialog.
(Additional columns are type, creator, date.)

- Select Defaults
This usefull action simply selects all listed apps that are registered to receive some
notification. This is usually a superset of the applications that should be locked.
You can still unselect applications that you deem to be safe.

- To change the sort order tap suitable column label.

- Browsing
You can move the cursor using 5way or by typing some character. (Use with the name sort order only.)
If multiple items are selected, 5way causes scrolling.


General Options dialog
-----------------------

Resco Locker can be disabled. In this case:	
	- The locked applications are unlocked.
	- The lock flags (icons) will be preserved and the user can continue marking apps as
	  locked/unlocked. However, these are just formal flags that will turn back to the real
	  locking after enabling Resco Locker.

Resco Locker can restore application locks on reset or clear all locks - depending on the option
the user selects. 

Only lock code in applications
If you select this option, then RLock will lock only the records that contain executable code.
The other records usually contain forms, bitmaps, strings etc. and are rarely used in the
background processing.
Omitting these records increases the free space in the DbCache.
(Or allows you to lock more databases.)


Database Attributes
-------------------

! - Receives Notifications
	The DB is registered to receive one of these notifications:
		SyncStart
		SyncFinish
		SleepRequest
		SleepNotify
		EarlyWakeup
		LateWakeup
		MenuCmdBarOpen
		DBDeleted
		DeleteProtected
		ProcessPenStroke
		VirtualCharHandling
		EventDequeued
		IdleTime

	The notifications can be received in 2 ways:
		- Via launch code:
		  This is a slow way, but safe. (OS will take care that the app is loaded.)
		- By direct calls into the application code:
		  This is fast and that's way used in background processing.
		  Such apps must be locked and protected.

	At present RLock cannot distinguish both notification types.

	Palm OS uses a lot more notifications, but the ones listed above are most frequent
	in the background processing. Those who want finer control over notifications are 
	advised to use these tools that show complete notification details:
		Palm Internals (freeware)
		Resco Explorer (since v2.70; provides richer information)

L - Locked
	Databases consist of records and the locking is done on the record basis. (Otherwise
	very large DBs would take up too much cache space.)
	Reset clears all locks.

	Locked means that at least one of the records is locked. The question still remains
	whether the right records are locked.
	E.g. in case of background apps it is necessary to lock the record containing the
	executable code that is carried out during the notification processing.

	Those who want complete record lock information have to use Resco Explorer.
	
O - Opened
	DB is in use.

XO - Exclusively Opened
	DB is in exclusive use and cannot be viewed or locked.

P - Protected
	This denotes a special status when a simple delete operation fails.
	As explained above, all apps receiving notifications via code must be protected.
	Therefore unprotected apps receiving notifications are potentially risky.


Which databases can be locked
-----------------------------

RLock started with applications and their databases and subsequently added preference panels
and DA's (plugins for DA launcher).

v1.31 added also RAM 'ovly' files that override some ROM database. This should help in cases
when the RAM override is flushed from the DbCache and Palm OS starts using the original ROM instance.

On the other hand, v1.31 stopped locking of the data databases on the new Palm handhelds.
(Discussed later bellow.)


Relation to other Resco products
--------------------------------

Resco Backup performs similar locking to stabilize the backup procedure. However, this locking
has just temporary influence without any impact onto another applications.

Resco Explorer can be used to check the locking details:
If you view a locked database, the combo-box displaying the record list shows also their lock count.
E.g.
	Code 1000 L2
denotes the code resource "Code 1000" that is locked twice.

Resco Explorer v2.70 offers also list of registered notifications details.


The risks
---------

One could envisage specific programming constructs that under specific occasions would conflict
with external locking as performed by Resco Locker. These constructs are not very probable, 
but cannot be excluded either. 

If you suspect RLocker to cause some problems during the initialization after reset:
Perform warm reset (this precludes initialization of the 3rd part apps), start RLocker
and correct the settings.

We do not have any user report that RLocker would cause any problem, but it is good to know
that there exist a safe workaround. (Which is applicable to many other apps as well.)


Conclusions
-----------

Resco Locker was created with the hope to help the users. 
However, Palm OS is an open system and bad interactions with the way RLocker works cannot be excluded. 
We don't want any money for this tool, but do not take any responsibility for eventual consequences. 
Use it with care


Contacts
--------

palm@resco-net.com



========================
	Remarks
========================


A note about hacks
-------------------

Classic hacks are pieces of code that are being executed by the installed hack manager.
If you use latest YAHM, then locking is not a question for hacks as YAHM works with duplicates
of original hacks fixed in the dynamic memory.


NVFS-related problems
----------------------

This chapter concerns NVFS-based handhelds. (At the time of writing: T5, T650, E2, LifeDrive.) 

What is NVFS?
Non-Volatile File Storage, i.e. a permanent storage that will survive even the battery removal. 

Unlike older Palm handhelds, databases are located in the NVFS storage and cannot be accessed directly.
Instead, they are accessed through a reserved RAM area called DbCache. 

It is a kind of window into NVFS: Prior to use the DB must be copied from NVFS to the DbCache and 
after the use the changes are copied back to NVFS and the DB may be removed from the DbCache 
to provide the space for other databases. For efficiency reasons the last step is delayed 
until the DbCache is full. 

DbCache is around 10 MB and you can have installed a lot more data in the RAM.
You can even have a single database that is larger than the whole DbCache.
This implies a fundamental consequence for the Palm programming: 
The position of the database or their records is no longer constant. 
Programs not realizing this will occasionally crash.

Many background applications that proved to work reliably in the past, are not NVFS-aware and can
cause a crash once the DbCache gets filled and the application is swapped.
Most users will attribute the crash to the application that is displayed on the screen
and which is in fact innocent.


Protected databases
-------------------

Protecting means that Palm OS refuses to delete the application. Instead, it sends a notification
to the app and if the app "agrees" (i.e. the app must deprotect itself), then the delete trial
is repeated.

This makes sense as it gives the chance to the application to properly terminate its activity.

Since the old days it is a tradition that background apps are
1. locked,
2. protected

Some apps ignored this convention as they thought they are safe.
Some apps ignored locking because of the same reason.
However, since NVFS arrived, locking is a must and since Palm TX protecting is required, too.


New Palm handhelds
-------------------

Since Palm TX (i.e. TX, T700p, T680) the meaning of locking has changed.
Locking itself is ignored by Palm OS unless the database is also protected.
On the other hand protecting a DB is a dangerous action - mainly for data databases. If an app
is not prepared to handle the protection, it might easily fail.
Therefore RLock performs only application locks leaving the data databases intact.
(Concerns only the above mentioned handhelds.)
